TypeScript konfigūracija: TSConfig kompiliatoriaus parinkčių valdymas

tsconfig.json failas yra bet kurio TypeScript projekto širdis. Jis nurodo, kaip TypeScript kompiliatorius (tsc) transformuoja jūsų .ts failus į JavaScript. Gerai sukonfigūruotas tsconfig.json yra gyvybiškai svarbus kodu kokybei palaikyti, suderinamumui tarp skirtingų aplinkų užtikrinti ir kompiliavimo procesui optimizuoti. Šis išsamus vadovas gilinasi į pažangias tsconfig.json parinktis, suteikdamas jums galimybę tiksliai sureguliuoti savo TypeScript projektus, kad būtų pasiektas didžiausias našumas ir palaikomumas.

Pagrindų supratimas: kodėl TSConfig yra svarbus

Prieš gilindamiesi į pažangias parinktis, prisiminkime, kodėl tsconfig.json yra toks svarbus:

• Kompiliavimo valdymas: Jis nurodo, kurie failai turi būti įtraukti į jūsų projektą ir kaip jie turi būti kompiliuojami.
• Tipų tikrinimas: Jis apibrėžia tipų tikrinimo taisykles ir griežtumą, padedant aptikti klaidas ankstyvame kūrimo cikle.
• Išvesties valdymas: Jis nustato tikslinę JavaScript versiją, modulių sistemą ir išvesties katalogą.
• IDE integravimas: Jis suteikia vertingos informacijos IDE (pvz., VS Code, WebStorm ir kt.) funkcijoms, tokioms kaip kodo užbaigimas, klaidų žymėjimas ir refaktoringas.

Be tsconfig.json failo, TypeScript kompiliatorius naudos numatytuosius nustatymus, kurie gali netikti visiems projektams. Tai gali sukelti netikėtą elgesį, suderinamumo problemas ir neidealią kūrimo patirtį.

TSConfig kūrimas: greitas pradžia

Norėdami sukurti tsconfig.json failą, tiesiog paleiskite šią komandą savo projekto šakniniame kataloge:

            tsc --init
            

              
                Copy
              
            
          

Tai sugeneruos pagrindinį tsconfig.json failą su kai kuriomis bendromis parinktimis. Tada galite tinkinti šį failą, kad atitiktumėte konkrečius savo projekto reikalavimus.

Pagrindinės kompiliatoriaus parinktys: išsami apžvalga

tsconfig.json faile yra compilerOptions objektas, kuriame konfigūruojate TypeScript kompiliatorių. Išnagrinėkime kai kurias svarbiausias ir dažniausiai naudojamas parinktis:

target

Ši parinktis nurodo ECMAScript tikslinę versiją sukompiliuotam JavaScript kodui. Ji nustato, kokias JavaScript funkcijas kompiliatorius naudos, užtikrindama suderinamumą su tiksline aplinka (pvz., naršyklėmis, Node.js). Dažniausiai naudojamos reikšmės yra ES5, ES6 (ES2015), ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Naudojant ESNext, bus taikomos naujausios palaikomos ECMAScript funkcijos.

Pavyzdys:

            "compilerOptions": {
  "target": "ES2020"
}
            

              
                Copy
              
            
          

Ši konfigūracija nurodys kompiliatoriui generuoti JavaScript kodą, suderinamą su ECMAScript 2020.

module

Ši parinktis nurodo modulių sistemą, kuri bus naudojama sukompiliuotame JavaScript kode. Dažniausiai naudojamos reikšmės yra CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 ir ESNext. Modulių sistemos pasirinkimas priklauso nuo tikslinės aplinkos ir naudojamo modulių įkėliklio (pvz., Node.js, Webpack, Browserify).

Pavyzdys:

            "compilerOptions": {
  "module": "CommonJS"
}
            

              
                Copy
              
            
          

Ši konfigūracija tinka Node.js projektams, kurie paprastai naudoja CommonJS modulių sistemą.

lib

Ši parinktis nurodo bibliotekos failų rinkinį, kuris bus įtrauktas į kompiliavimo procesą. Šie bibliotekos failai pateikia tipų apibrėžimus įdiegtoms JavaScript API ir naršyklės API. Dažniausiai naudojamos reikšmės yra ES5, ES6, ES7, DOM, WebWorker, ScriptHost ir kt.

Pavyzdys:

            "compilerOptions": {
  "lib": ["ES2020", "DOM"]
}
            

              
                Copy
              
            
          

Ši konfigūracija apima ECMAScript 2020 ir DOM API tipų apibrėžimus, kurie yra būtini naršyklės pagrindu veikiantiems projektams.

allowJs

Ši parinktis leidžia TypeScript kompiliatoriui kompiliuoti JavaScript failus kartu su TypeScript failais. Tai gali būti naudinga migruojant JavaScript projektą į TypeScript arba dirbant su esamomis JavaScript kodų bazėmis.

Pavyzdys:

            "compilerOptions": {
  "allowJs": true
}
            

              
                Copy
              
            
          

Įjungus šią parinktį, kompiliatorius apdoros tiek .ts, tiek .js failus.

checkJs

Ši parinktis įjungia tipų tikrinimą JavaScript failams. Sujungus su allowJs, ji leidžia TypeScript nustatyti galimas tipų klaidas jūsų JavaScript kode.

Pavyzdys:

            "compilerOptions": {
  "allowJs": true,
  "checkJs": true
}
            

              
                Copy
              
            
          

Ši konfigūracija užtikrina tipų tikrinimą tiek TypeScript, tiek JavaScript failams.

jsx

Ši parinktis nurodo, kaip turi būti transformuojama JSX sintaksė (naudojama React ir kituose karkasuose). Dažniausiai naudojamos reikšmės yra preserve, react, react-native ir react-jsx. preserve palieka JSX sintaksę tokią, kokia ji yra, react transformuoja ją į React.createElement iškvietimus, react-native skirta React Native kūrimui, o react-jsx transformuoja ją į JSX gamyklos funkcijas. react-jsxdev yra skirta kūrimo tikslams.

Pavyzdys:

            "compilerOptions": {
  "jsx": "react"
}
            

              
                Copy
              
            
          

Ši konfigūracija tinka React projektams, transformuojantiems JSX į React.createElement iškvietimus.

declaration

Ši parinktis generuoja deklaracijos failus (.d.ts) jūsų TypeScript kodui. Deklaracijos failai teikia tipų informaciją jūsų kodui, leidžiant kitiems TypeScript projektams arba JavaScript projektams naudoti jūsų kodą su tinkamu tipų tikrinimu.

Pavyzdys:

            "compilerOptions": {
  "declaration": true
}
            

              
                Copy
              
            
          

Ši konfigūracija generuos .d.ts failus kartu su sukompiliuotais JavaScript failais.

declarationMap

Ši parinktis generuoja šaltinio žemėlapių failus (.d.ts.map) generuojamiems deklaracijos failams. Šaltinio žemėlapiai leidžia derintuvams ir kitiems įrankiams grįžti prie originalaus TypeScript šaltinio kodo, dirbant su deklaracijos failais.

Pavyzdys:

            "compilerOptions": {
  "declaration": true,
  "declarationMap": true
}
            

              
                Copy
              
            
          

sourceMap

Ši parinktis generuoja šaltinio žemėlapių failus (.js.map) sukompiliuotam JavaScript kodui. Šaltinio žemėlapiai leidžia derintuvams ir kitiems įrankiams grįžti prie originalaus TypeScript šaltinio kodo, derinant naršyklėje ar kitose aplinkose.

Pavyzdys:

            "compilerOptions": {
  "sourceMap": true
}
            

              
                Copy
              
            
          

outFile

Ši parinktis sujungia ir išleidžia visus išvesties failus į vieną failą. Tai paprastai naudojama kodo sujungimui naršyklės pagrindu veikiančioms programoms.

Pavyzdys:

            "compilerOptions": {
  "outFile": "dist/bundle.js"
}
            

              
                Copy
              
            
          

outDir

Ši parinktis nurodo išvesties katalogą sukompiliuotiems JavaScript failams. Jei nenurodyta, kompiliatorius išvesties failus patalpins tame pačiame kataloge kaip ir šaltinio failus.

Pavyzdys:

            "compilerOptions": {
  "outDir": "dist"
}
            

              
                Copy
              
            
          

Ši konfigūracija patalpins sukompiliuotus JavaScript failus į dist katalogą.

rootDir

Ši parinktis nurodo TypeScript projekto šakninį katalogą. Kompiliatorius naudoja šį katalogą modulių pavadinimams išspręsti ir išvesties failų keliams generuoti. Tai ypač naudinga sudėtingoms projekto struktūroms.

Pavyzdys:

            "compilerOptions": {
  "rootDir": "src"
}
            

              
                Copy
              
            
          

removeComments

Ši parinktis pašalina komentarus iš sukompiliuoto JavaScript kodo. Tai gali padėti sumažinti išvesties failų dydį.

Pavyzdys:

            "compilerOptions": {
  "removeComments": true
}
            

              
                Copy
              
            
          

noEmitOnError

Ši parinktis neleidžia kompiliatoriui išleisti JavaScript failų, jei aptinkamos kokios nors tipų klaidos. Tai užtikrina, kad būtų generuojamas tik galiojantis kodas.

Pavyzdys:

            "compilerOptions": {
  "noEmitOnError": true
}
            

              
                Copy
              
            
          

strict

Ši parinktis įjungia visas griežtas tipų tikrinimo parinktis. Tai labai rekomenduojama naujiems projektams, nes tai padeda aptikti galimas klaidas ir taikyti geriausią praktiką.

Pavyzdys:

            "compilerOptions": {
  "strict": true
}
            

              
                Copy
              
            
          

Griežto režimo įjungimas prilygsta šių parinkčių įjungimui:

• noImplicitAny
• noImplicitThis
• alwaysStrict
• strictNullChecks
• strictFunctionTypes
• strictBindCallApply
• noImplicitReturns
• noFallthroughCasesInSwitch

esModuleInterop

Ši parinktis įgalina CommonJS ir ES modulių sąveiką. Ji leidžia importuoti CommonJS modulius į ES modulius ir atvirkščiai.

Pavyzdys:

            "compilerOptions": {
  "esModuleInterop": true
}
            

              
                Copy
              
            
          

forceConsistentCasingInFileNames

Ši parinktis užtikrina nuoseklų didžiųjų ir mažųjų raidžių naudojimą failų pavadinimuose. Tai svarbu tarp-platforminiam suderinamumui, nes kai kurios operacinės sistemos skiria didžiąsias ir mažąsias raides, o kitos – ne.

Pavyzdys:

            "compilerOptions": {
  "forceConsistentCasingInFileNames": true
}
            

              
                Copy
              
            
          

baseUrl ir paths

Šios parinktys leidžia konfigūruoti modulių išskyrimą. baseUrl nurodo bazinį katalogą, skirtą ne-santykiniais modulių pavadinimams išspręsti, o paths leidžia apibrėžti pasirinktinius modulių aliasus.

Pavyzdys:

            "compilerOptions": {
  "baseUrl": ".",
  "paths": {
    "@components/*": ["src/components/*"],
    "@utils/*": ["src/utils/*"]
  }
}
            

              
                Copy
              
            
          

Ši konfigūracija leidžia importuoti modulius naudojant aliasus, tokius kaip @components/MyComponent ir @utils/myFunction.

Pažangi konfigūracija: daugiau nei pagrindai

Dabar panagrinėkime kai kurias pažangias tsconfig.json parinktis, kurios gali dar labiau pagerinti jūsų TypeScript kūrimo patirtį.

Inkrementinis kompiliavimas

TypeScript palaiko inkrementinį kompiliavimą, kuris gali žymiai paspartinti didelių projektų kūrimo procesą. Norėdami įjungti inkrementinį kompiliavimą, nustatykite parinktį incremental į true ir nurodykite tsBuildInfoFile parinktį.

Pavyzdys:

            "compilerOptions": {
  "incremental": true,
  "tsBuildInfoFile": ".tsbuildinfo"
}
            

              
                Copy
              
            
          

Parinktis tsBuildInfoFile nurodo failą, kuriame kompiliatorius saugos kompiliavimo informaciją. Ši informacija naudojama nustatyti, kuriuos failus reikia iš naujo sukompiliuoti vėlesnių kompiliavimų metu.

Projekto nuorodos

Projekto nuorodos leidžia struktūrizuoti kodą į mažesnius, lengviau valdomus projektus. Tai gali pagerinti kompiliavimo laiką ir kodo organizavimą didelėse kodų bazėse. Gera analogija šiai koncepcijai yra mikroservisų architektūra – kiekviena paslauga yra nepriklausoma, bet priklauso nuo kitų ekosistemoje.

Norėdami naudoti projekto nuorodas, turite sukurti atskirą tsconfig.json failą kiekvienam projektui. Tada pagrindiniame tsconfig.json faile galite nurodyti projektus, į kuriuos turėtų būti nuorodos, naudodami references parinktį.

Pavyzdys:

            {
  "compilerOptions": {
    ...
  },
  "references": [
    { "path": "./project1" },
    { "path": "./project2" }
  ]
}
            

              
                Copy
              
            
          

Ši konfigūracija nurodo, kad dabartinis projektas priklauso nuo projektų, esančių ./project1 ir ./project2 kataloguose.

Pasirinktiniai transformeriai

Pasirinktiniai transformeriai leidžia modifikuoti TypeScript kompiliatoriaus išvestį. Tai gali būti naudojama įvairiems tikslams, pvz., pridėti pasirinktines kodo transformacijas, pašalinti nenaudojamą kodą arba optimizuoti išvestį konkrečioms aplinkoms. Jie dažniausiai naudojami i18n internacionalizavimo ir lokalizavimo užduotims.

Norėdami naudoti pasirinktinius transformatorius, turite sukurti atskirą JavaScript failą, kuris eksportuoja funkciją, kurią iškvies kompiliatorius. Tada galite nurodyti transformatoriaus failą naudodami plugins parinktį tsconfig.json faile.

Pavyzdys:

            {
  "compilerOptions": {
    ...
    "plugins": [
      { "transform": "./transformer.js" }
    ]
  }
}
            

              
                Copy
              
            
          

Ši konfigūracija nurodo, kad ./transformer.js failas turėtų būti naudojamas kaip pasirinktinis transformatorius.

Failai, Įtraukti ir Išskirti

Be compilerOptions, kitos šakninio lygio parinktys tsconfig.json faile kontroliuoja, kurie failai įtraukiami į kompiliavimo procesą:

• files: Failų kelių masyvas, skirtas įtraukti į kompiliavimą.
• include: Glob šablonų masyvas, nurodantis failus, kuriuos reikia įtraukti.
• exclude: Glob šablonų masyvas, nurodantis failus, kuriuos reikia išskirti.

Šios parinktys suteikia smulkų valdymą, kurie failai apdorojami TypeScript kompiliatoriaus. Pavyzdžiui, galite pašalinti testavimo failus arba sugeneruotą kodą iš kompiliavimo proceso.

Pavyzdys:

            {
  "compilerOptions": { ... },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

Ši konfigūracija apima visus failus src kataloge ir jo pakatalogiuose, išskyrus failus node_modules ir dist kataloguose, taip pat visus failus su plėtiniu .spec.ts (paprastai naudojami vieneto testams).

Kompiliatoriaus parinktys specifiniams scenarijams

Skirtingiems projektams gali prireikti skirtingų kompiliatoriaus nustatymų, kad būtų pasiekti optimalūs rezultatai. Panagrinėkime keletą konkrečių scenarijų ir rekomenduojamus kompiliatoriaus nustatymus kiekvienam iš jų.

Žiniatinklio programų kūrimas

Kuriant žiniatinklio programas, paprastai norėsite naudoti šiuos kompiliatoriaus nustatymus:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Node",
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "sourceMap": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

Šie nustatymai tinka modernioms žiniatinklio programoms, naudojančioms React ar kitus panašius karkasus. Jie orientuoti į naujausias ECMAScript funkcijas, naudoja ES modulius ir įgalina griežtą tipų tikrinimą.

Node.js galinės sistemos (backend) kūrimas

Kuriant Node.js galinę sistemą (backend), paprastai norėsite naudoti šiuos kompiliatoriaus nustatymus:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "CommonJS",
    "esModuleInterop": true,
    "strict": true,
    "sourceMap": true,
    "outDir": "dist",
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

Šie nustatymai tinka Node.js programoms, naudojančioms CommonJS modulių sistemą. Jie orientuoti į naujausias ECMAScript funkcijas, įgalina griežtą tipų tikrinimą ir leidžia importuoti JSON failus kaip modulius.

Bibliotekų kūrimas

Kuriant bibliotekas, paprastai norėsite naudoti šiuos kompiliatoriaus nustatymus:

            {
  "compilerOptions": {
    "target": "ES5",
    "module": "UMD",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

Šie nustatymai tinka kuriant bibliotekas, kurias galima naudoti tiek naršyklės, tiek Node.js aplinkose. Jie generuoja deklaracijos failus ir šaltinio žemėlapius, siekiant pagerinti kūrėjo patirtį.

Geriausia TSConfig valdymo praktika

Štai keletas geriausių praktikų, kurių reikėtų laikytis tvarkant savo tsconfig.json failus:

• Pradėkite nuo bazinės konfigūracijos: Sukurkite bazinį tsconfig.json failą su bendraisiais nustatymais ir tada išplėskite jį kituose projektuose naudodami extends parinktį.
• Naudokite griežtą režimą: Įjunkite griežtą režimą, kad aptiktumėte galimas klaidas ir taikytumėte geriausią praktiką.
• Konfigūruokite modulių išskyrimą: Tinkamai sukonfigūruokite modulių išskyrimą, kad išvengtumėte importavimo klaidų.
• Naudokite projekto nuorodas: Struktūruokite savo kodą į mažesnius, lengviau valdomus projektus, naudodami projekto nuorodas.
• Reguliariai atnaujinkite savo tsconfig.json failą: Reguliariai peržiūrėkite savo tsconfig.json failą ir atnaujinkite jį, keičiantis projektui.
• Versijuokite savo tsconfig.json failą: Įkelkite savo tsconfig.json failą į versijų valdymo sistemą kartu su kitais šaltinio kodais.
• Dokumentuokite savo konfigūraciją: Pridėkite komentarų prie savo tsconfig.json failo, kad paaiškintumėte kiekvienos parinkties paskirtį.

Išvada: TypeScript konfigūracijos valdymas

tsconfig.json failas yra galingas įrankis, skirtas konfigūruoti TypeScript kompiliatorių ir valdyti kompiliavimo procesą. Suprasdami galimas parinktis ir laikydamiesi geriausios praktikos, galite tiksliai sureguliuoti savo TypeScript projektus, kad būtų pasiektas optimalus našumas, palaikomumas ir suderinamumas. Šis vadovas pateikė išsamią pažangių parinkčių, esančių tsconfig.json faile, apžvalgą, suteikdamas jums galimybę visiškai kontroliuoti savo TypeScript kūrimo darbo eigą. Visada prisiminkite pasikonsultuoti su oficialia TypeScript dokumentacija, kad gautumėte naujausią informaciją ir gaires. Tobulėjant jūsų projektams, turėtų tobulėti ir jūsų supratimas bei šių galingų konfigūracijos įrankių naudojimas. Sėkmingo programavimo!